IXTRACE

Section: User Commands (1)
Index Return to Main Contents

NAME

ixtrace - a tracer for ixemul.library

SYNOPSIS

ixtrace [ -a ] [ -i ] [ -m ] [ -l ] [ -v ] [ -z ] [ -c syscall name ] [ -n N ] [ -o logfile ] [ -p pid ] [ -s syscall-number ]

DESCRIPTION

Ixtrace is a utility that reports every call that is made to the ixemul.library. Since it scans every call made through the library base, it catches even more calls than for example SnoopDOS.

Obviously, tracing support slows down all clients of the library (as each call is now routed through a trace function). For this reason there are two library versions. Ixemul.library itself doesn't contain tracing support. Using the tracer with this library gives a "Function not implemented" error. To use the ixtrace utility, you should use the ixemul.trace library instead of ixemul.library. See USAGE for more detailed instructions.

The option most often used is -m, as the library uses sigsetmask() a lot internally, and mentioning this call again and again would just clutter the screen.

OPTIONS

-a: Print all calls, even those considered `not interesting': internal stdio-calls and 32 bit arithmetic emulation for 68000, for example.
-i: Normally, the tracer shows a function call when that function returns, to be able to display the return value (and errno in parenthesis). When -i is specified, it always displays the function on entry, instead of on exit. See BUGS for current problems if you invoke ixtrace without the -i option.
-m: Skip sigsetmask() calls. This function is used extensively inside the library, and will in most cases just clutter the tracer output.
-l: List all system calls to stdout. No more need to look up a call you want to trace in the include/sys/syscall.def file.
-v: Print the current version number.
-z: Allows the input of syscall names that the user wants to trace.
-c: Only print calls to a specific system call, by name. Differs from -s , which expects a syscall number.
-n: Skip the first N traces.
-o: Specify a logfile. If -o is omitted, output goes to stdout.
-p: Only print output from a specific process. You have to provide the decimal address of the process. Default is to scan all current ixemul.library clients.
-s: Only print calls to a specific system call. You have to specify the system call number as found in <sys/syscalls.def>.

USAGE

Before you can use ixtrace, you will first have to flush the old ixemul.library out of the system. The Workbench option FlushLibs can do that for you, Avail FLUSH achieves the same from a shell. This assumes no currently running process is using the library.

Next make sure the system loads ixemul.trace instead of ixemul.library next time it starts a program that uses ixemul.library

You can do that by replacing ixemul.library with ixemul.trace. You can also use LoadLib ixemul.trace. But LoadLib is not an official CLI command.

Now Start the tracer (probably in its own window). You should now see a log of all functions called from your program(s), and some functions called as a consequence of your functions from inside the library. A typical output line is:

$7588790: <strcmp(foo, -n)=57 (0)

$7588790: This is the process address.
<: Type of log, < means on exit, > means on entry.
strcmp(foo, -n): The function with the parameters.
=57: The result of the function.
(0): The value of errno.

BUGS

There seems to be some race condition, that can result in deadlock when running without the -i flag.

Currently, if trace-on-exit is enabled, the function is called with 16 arguments, no matter how many arguments you passed to it. This should be enough for 99% of all applications, but you may have more than 16 arguments to a printf() somewhere.

Functions returning more than a 4 byte result do not work unless you specify the -i option!

HISTORY

Adapted by David Zaroski from the original README written by Markus Wild.

This document was created by man2html, using the manual pages.
Time: 19:42:02 GMT, December 25, 2022